home *** CD-ROM | disk | FTP | other *** search
/ Aminet 2 / Aminet AMIGA CDROM (1994)(Walnut Creek)[Feb 1994][W.O. 44790-1].iso / Aminet / dev / misc / sflib14.lha / screenfool.doc < prev    next >
Encoding:
Text File  |  1993-09-12  |  13.0 KB  |  489 lines
  1. TABLE OF CONTENTS
  2.  
  3. screenfool.library/AllocSFList
  4. screenfool.library/ClearDisplayList
  5. screenfool.library/ClearPubScreenList
  6. screenfool.library/ClosePublicScreen
  7. screenfool.library/DeallocSFList
  8. screenfool.library/FindDisplayID
  9. screenfool.library/FindDisplayMode
  10. screenfool.library/FindDMInList
  11. screenfool.library/FindScreenInList
  12. screenfool.library/NewDisplayList
  13. screenfool.library/NewPubScreenList
  14. screenfool.library/OpenPublicScreenA
  15. screenfool.library/StandardizeDisplayID
  16. screenfool.library/AllocSFList                 screenfool.library/AllocSFList
  17.  
  18.    NAME   
  19.         AllocSFList -- Allocate a SFList structure.
  20.  
  21.    SYNOPSIS
  22.         sflist=AllocSFList(type);
  23.           D0                D0
  24.  
  25.         struct ScreenFoolList *AllocSFList(UBYTE);
  26.  
  27.    FUNCTION
  28.         Allocates a new SFList structure. These MUST be allocated by
  29.         screenfool.library. You MAY NOT AllocMem() a ScreenFoolList.
  30.  
  31.    INPUTS
  32.         type - One of sfNT_DISPLAY or sfNT_SCREEN.
  33.  
  34.    RESULT
  35.         sflist - An initialized ScreenFoolList structure.
  36.                  NULL indicates that not enough memory was available.
  37.  
  38.    EXAMPLE
  39.  
  40.    NOTES
  41.  
  42.    BUGS
  43.  
  44.    SEE ALSO
  45.         DeallocSFList(), <libraries/screenfool.h>
  46.  
  47. screenfool.library/ClearDisplayList       screenfool.library/ClearDisplayList
  48.  
  49.    NAME   
  50.         ClearDisplayList -- Clear the viewmode listing
  51.  
  52.    SYNOPSIS
  53.         ClearDisplayList(dmilist);
  54.                            A0
  55.  
  56.         void ClearDisplayList(struct ScreenFoolList *);
  57.  
  58.    FUNCTION
  59.         Initialize the display viewmode list, by clearing any existing
  60.         entries, and preparing for a call to NewDisplayList().
  61.  
  62.         This does not deallocate the ScreenFoolList structure. See the
  63.         function DeallocSFList().
  64.  
  65.    INPUTS
  66.         dmlist - A pointer to a ScreenFoolList structure.
  67.  
  68.    RESULT
  69.         None
  70.  
  71.    EXAMPLE
  72.  
  73.    NOTES
  74.  
  75.    BUGS
  76.  
  77.    SEE ALSO
  78.         NewDisplayList(), AllocSFList(), DeallocSFList()
  79.  
  80. screenfool.library/ClearPubScreenList   screenfool.library/ClearPubScreenList
  81.  
  82.    NAME   
  83.         ClearPubScreenList -- Clear the public screen list.
  84.  
  85.    SYNOPSIS
  86.         ClearPublicScreenList(pslist);
  87.                                 A0
  88.  
  89.         void ClearPubScreenList(struct ScreenFoolList *);
  90.  
  91.    FUNCTION
  92.         Clears the public screen list, releasing the allocated memory back
  93.         to the operating system.
  94.  
  95.         This does *not* deallocate the ScreenFoolList structure. See the
  96.         function DeallocSFList()
  97.  
  98.    INPUTS
  99.         pslist - The screen list you want to empty
  100.  
  101.    RESULT
  102.         None
  103.  
  104.    EXAMPLE
  105.  
  106.    NOTES
  107.  
  108.    BUGS
  109.  
  110.    SEE ALSO
  111.         NewPubScreenList(), AllocSFList(), DeallocSFList()
  112.  
  113. screenfool.library/ClosePublicScreen     screenfool.library/ClosePublicScreen
  114.  
  115.    NAME   
  116.         ClosePublicScreen -- Close a public screen
  117.  
  118.    SYNOPSIS
  119.         ok = ClosePublicScreen(Name)
  120.         D0                      A0
  121.  
  122.         BOOL ClosePublicScreen(STRPTR);
  123.  
  124.    FUNCTION
  125.         Close the public screen specified by Name.
  126.  
  127.    INPUTS
  128.         Name - Pointer to a vaild Public Screen name
  129.  
  130.    RESULT
  131.         ok - As intuition.library/CloseScreen()
  132.              TRUE - Closed OK
  133.              FALSE - Couldn't close screen -- a visitor window is
  134.                      probably still open on the screen.
  135.  
  136.    EXAMPLE
  137.  
  138.    NOTES
  139.         This screen does not have to have been opened by screenfool.library
  140.  
  141.    BUGS
  142.  
  143.    SEE ALSO
  144.         <intuituion/screens.h>, intuition.library/OpenScreen(),
  145.         OpenPublicScreen(), intuition.library/CloseScreen()
  146.  
  147. screenfool.library/DeallocSFList             screenfool.library/DeallocSFList
  148.  
  149.    NAME   
  150.         DeallocSFList -- Deallocate a SFList structure.
  151.  
  152.    SYNOPSIS
  153.         ok=DeallocSFList(sflist);
  154.         D0                 A0
  155.  
  156.         BOOL DeallocSFList(struct ScreenFoolList *);
  157.  
  158.    FUNCTION
  159.         Deallocates a SFList structure. This MUST have been allocated by
  160.         screenfool.library. Don't just FreeMem this structure!
  161.  
  162.    INPUTS
  163.         sflist - A ScreenFoolList that has been cleared by the appropriate
  164.                  Clear#?List function.
  165.  
  166.    RESULT
  167.         ok - TRUE if the list could be deallocated.
  168.              FALSE if not.
  169.  
  170.    EXAMPLE
  171.  
  172.    NOTES
  173.  
  174.    BUGS
  175.  
  176.    SEE ALSO
  177.         AllocSFList(), ClearDisplayList(), ClearPubScreenList()
  178.  
  179. screenfool.library/FindDisplayID             screenfool.library/FindDisplayID
  180.  
  181.    NAME   
  182.         FindDisplayID -- Find the DisplayModeInfo for a DisplayID
  183.  
  184.    SYNOPSIS
  185.         dmi = FindDisplayID(dmilist, DisplayID)
  186.         D0                    A0        D0
  187.  
  188.         struct DisplayModeInfo *FindDisplayID(struct ScreenFoolList *,
  189.                                               ULONG);
  190.  
  191.    FUNCTION
  192.         Find and return the DisplayModeInfo structure associated with
  193.         a DisplayID. This can be a generic or absolute (monitor-specific)
  194.         identifier.
  195.  
  196.    INPUTS
  197.         dmilist - A previously initialized list from NewDisplayList()
  198.         DisplayID - A 32-bit display identifier
  199.  
  200.    RESULT
  201.         dmi - A pointer to the appropriate DisplayModeInfo record, or NULL
  202.           if the DisplayID was invalid for this system, or was not in the
  203.           list (due to property exclusion).
  204.  
  205.    EXAMPLE
  206.  
  207.    NOTES
  208.         Only available display identifiers are valid.
  209.  
  210.    BUGS
  211.  
  212.    SEE ALSO
  213.         NewDisplayList(), FindDMInList(), FindDisplayMode(),
  214.         <graphics/displaymode.h>, graphics.library/ModeNotAvailable()
  215.  
  216. screenfool.library/FindDisplayMode         screenfool.library/FindDisplayMode
  217.  
  218.    NAME   
  219.         FindDisplayMode -- Find the position of a DisplayModeInfo
  220.  
  221.    SYNOPSIS
  222.         position = FindDisplayMode(dmilist, dmi);
  223.            D0                        A0     A1
  224.  
  225.         ULONG FindDisplayMode(struct ScreenFoolList *, 
  226.                               struct DisplayModeInfo *);
  227.  
  228.    FUNCTION
  229.         Find and return the position of the display mode record in
  230.         the display mode listing.
  231.  
  232.    INPUTS
  233.         dmilist - A previously initialized list from NewDisplayList()
  234.         dmi - A display mode record (must be from dmilist - you can't
  235.             create your own!)
  236.  
  237.    RESULT
  238.         position - The position of the display mode record in the list.
  239.  
  240.    EXAMPLE
  241.  
  242.    NOTES
  243.  
  244.    BUGS
  245.  
  246.    SEE ALSO
  247.         NewDisplayList(), FindDMInList(), FindDisplayID()
  248.  
  249. screenfool.library/FindDMInList               screenfool.library/FindDMInList
  250.  
  251.    NAME   
  252.         FindDMInList -- Find the display mode from a listview pos.
  253.  
  254.    SYNOPSIS
  255.         dmi = FindDMInList(dmilist, position);
  256.         D0                   A0        D0
  257.  
  258.         struct DisplayModeInfo *FindDMInList(struct ScreenFoolList *,
  259.                                              ULONG);
  260.  
  261.    FUNCTION
  262.         Find the DisplayModeInfo structure of the ordinal'th item in
  263.         the list.
  264.  
  265.    INPUTS
  266.         dmilist - A previously initialized list from NewDisplayList()
  267.         position - The list position
  268.  
  269.    RESULT
  270.         dmi - A pointer to the DisplayModeInfo record.
  271.  
  272.    EXAMPLE
  273.  
  274.    NOTES
  275.  
  276.    BUGS
  277.  
  278.    SEE ALSO
  279.         NewDisplayList(), FindDisplayID(), FindDisplayMode()
  280.  
  281. screenfool.library/FindScreenInList       screenfool.library/FindScreenInList
  282.  
  283.    NAME   
  284.         FindScreenInList -- Find screen node in a list, given its pos.
  285.  
  286.    SYNOPSIS
  287.         psinfo = FindScreenInList(pslist, position);
  288.           D0                        A0       D0
  289.  
  290.         struct PublicScreenInfo *FindScreenInList(struct ScreenFoolList *,
  291.                                  ULONG);
  292.  
  293.    FUNCTION
  294.         Find a screen in the given public screen list, and then return
  295.         its address. This is used for things like ListViews.
  296.  
  297.    INPUTS
  298.         pslist - An initialized ScreenFoolList header.
  299.         position - The ordinal position of
  300.  
  301.    RESULT
  302.         A pointer to the PublicScreenInfo structure that is associated
  303.         with this position. A too-large position will return NULL.
  304.  
  305.    EXAMPLE
  306.  
  307.    NOTES
  308.  
  309.    BUGS
  310.  
  311.    SEE ALSO
  312.         NewPubScreenList()
  313.  
  314. screenfool.library/NewDisplayList           screenfool.library/NewDisplayList
  315.  
  316.    NAME   
  317.         NewDisplayList -- Find available display modes
  318.  
  319.    SYNOPSIS
  320.         ok = NewDisplayList(dmilist, excludeProperties);
  321.         D0                    A0            D0
  322.  
  323.         BOOL NewDisplayList(struct ScreenFoolList *, ULONG);
  324.  
  325.    FUNCTION
  326.         Find all available screen display options, and load them into
  327.         the list. These must eventually be deallocated by calling the
  328.         ClearDisplayList() function. Will mask out duplicate displays
  329.         and will exclude viewmodes that posess properties masked by
  330.         the excludeProperties flag longword.
  331.  
  332.         If there are records already in the list, they will be auto-
  333.         magically removed.
  334.  
  335.    INPUTS
  336.         dmilist - Pointer to a ScreenFoolList
  337.  
  338.         excludeProperties - OR in flags of properties you DON'T want
  339.                             to see in the list.
  340.  
  341.    RESULT
  342.         ok - TRUE if list allocated correctly; FALSE otherwise
  343.  
  344.    EXAMPLE
  345.  
  346.    NOTES
  347.         This list is READ-ONLY. No messing.
  348.  
  349.         Nameless display modes that meet your criteria receive the name
  350.         "ID: 0x<hex display ID>".
  351.  
  352.    BUGS
  353.  
  354.    SEE ALSO
  355.         ClearDisplayList(), <graphics/displayinfo.h>
  356.  
  357. screenfool.library/NewPubScreenList       screenfool.library/NewPubScreenList
  358.  
  359.    NAME   
  360.         NewPubScreenList -- Obtain a list of all available pub. screens
  361.  
  362.    SYNOPSIS
  363.         ok = NewPubScreenList(pslist);
  364.         D0                      A0
  365.  
  366.         BOOL NewPubScreenList(struct ScreenFoolList *);
  367.  
  368.    FUNCTION
  369.         Find every available public screen on the system public screen
  370.         list, get some info on it, and put it in our private list.
  371.  
  372.         If the list is not empty, it will be cleared.
  373.  
  374.    INPUTS
  375.         pslist - A full ScreenFoolList header.
  376.  
  377.    RESULT
  378.         ok - TRUE if list allocated correctly; FALSE otherwise.
  379.  
  380.    EXAMPLE
  381.  
  382.    NOTES
  383.         Must be cleared after use by ClearPubScreenList()
  384.  
  385.         The only permissible uses for this list are read-only. DO NOT
  386.         WRITE TO THIS LIST, ADD OR REMOVE NODES, OR OTHERWISE ALTER ITS
  387.         CONTENTS. Screenfool's list protection is not that sophisticated,
  388.         so don't mess with it.
  389.  
  390.         DON'T mix up a display mode list with a screen list. There is some
  391.         error checking, but don't risk it.
  392.  
  393.    BUGS
  394.  
  395.    SEE ALSO
  396.         <intuituion/screens.h>, intuition.library/LockPubScreenList(),
  397.         intuition.library/GetScreenDrawInfo(), OpenPublicScreenA(),
  398.         intuition.library/CloseScreen(), intuition.library/OpenScreen(),
  399.         ClearPubScreenList(), <libraries/screenfool.h>
  400.  
  401. screenfool.library/OpenPublicScreenA     screenfool.library/OpenPublicScreenA
  402.  
  403.    NAME   
  404.         OpenPublicScreenA -- Open a public screen & make it non-private
  405.  
  406.    SYNOPSIS
  407.         screen = OpenPublicScreenA(Name, TagList);
  408.           D0                        A0      A1
  409.  
  410.         struct Screen *OpenPublicScreenA(STRPTR, struct TagItem *);
  411.  
  412.         VarArgs version (SAS/C 6.0 #pragma tagcall):
  413.  
  414.         struct Screen *OpenPublicScreen(STRPTR,
  415.                          tag, data, tag, data, ..., TAG_DONE);
  416.  
  417.    FUNCTION
  418.         Open a public screen in the specified display mode, and set it to
  419.         be accessable from other tasks.
  420.  
  421.    INPUTS
  422.         Name - A string that contains a valid, unused public screen name.
  423.         TagList - Additional tags for this screen.
  424.  
  425.    RESULT
  426.         screen - Pointer to a struct Screen. DO NOT CLOSE THIS USING
  427.                  intuition.library/CloseScreen()!!! Use:
  428.                        ok=ClosePublicScreen(screen);
  429.  
  430.    EXAMPLE
  431.  
  432.    NOTES
  433.         The screen title will be set to the public screen name. You can
  434.         override this behavior by using an SA_Title tag in your taglist.
  435.         Note that this title WILL NOT be protected or deallocated by
  436.         the library.
  437.  
  438.         Screen options MUST be supplied via Tags. There is no support
  439.         (present OR future) for NewScreen or ExtNewScreen structures.
  440.  
  441.         You may NOT use screen->UserData! This is the only pointer to
  442.         the screenfool.library tracking, which is necessary to recover
  443.         the memory used by OpenPublicScreen().
  444.  
  445.    BUGS
  446.  
  447.    SEE ALSO
  448.         NewDisplayList(), <graphics/displayinfo.h>, <intuituion/screens.h>,
  449.         ClosePublicScreen(), intuition.library/OpenScreen()
  450.  
  451. screenfool.library/StandardizeDisplayIDcreenfool.library/StandardizeDisplayID
  452.  
  453.    NAME   
  454.         StandardizeDisplayID -- Convert a generic display identifier
  455.            to a monitor-specific one.
  456.  
  457.    SYNOPSIS
  458.         AbsDisplayID = StandardizeDisplayID(DisplayID);
  459.              D0                                D0
  460.  
  461.         ULONG StandardizeDisplayID(ULONG);
  462.  
  463.    FUNCTION
  464.         Converts generic display identifiers to their monitor-specific
  465.         equivalents. This function uses Mode Promotion (under 3.0) and
  466.         the PAL/NTSC setting to find the best available mode to display
  467.         this type of display.
  468.  
  469.    INPUTS
  470.         DisplayID - A 32-bit display identifier
  471.  
  472.    RESULT
  473.         AbsDisplayID - A 32-bit display identifier
  474.  
  475.    EXAMPLE
  476.  
  477.    NOTES
  478.         You may supply an absolute identifier, in which case it returns
  479.         the same identifier (if internal) or a system-defined result.
  480.  
  481.         You may supply a display ID that is in the internal database but
  482.         unavailable.
  483.  
  484.    BUGS
  485.  
  486.    SEE ALSO
  487.         graphics.library/GetDisplayInfoData(), <graphics/displaymodes.h>
  488.  
  489.